Add referrer with annotations for image source and base image name + digest by lbussell · Pull Request #2163 · dotnet/docker-tools

lbussell · 2026-07-01T01:04:00Z

Part of #1602.

This PR attaches ImageBuilder build metadata to each newly built and pushed platform image as an OCI referrer artifact. The metadata is stored as annotations on the referrer manifest rather than as Docker image labels, so it does not get inherited by downstream images.

The referrer uses this artifact type:

application/vnd.microsoft.imagebuilder.image-info.v1

Annotation	Example value
`vnd.microsoft.imagebuilder.source`	`https://github.com/dotnet/docker-tools`
`vnd.microsoft.imagebuilder.revision`	`c0ffeec0ffeec0ffee...`
`vnd.microsoft.imagebuilder.base.name`	`mcr.microsoft.com/dotnet/runtime:9.0-azurelinux3.0`
`vnd.microsoft.imagebuilder.base.digest`	`sha256:abcdef123456...`
`vnd.microsoft.imagebuilder.dockerfile`	`src/Dockerfile.linux`

The Dockerfile annotation contains the path to the Dockerfile that the image was built from, relative to the repo root. This maintains parity with what's tracked in ImageArtifactDetails/image-info.json without baking the metadata into the image config.

Change to the build command's execution flow

While the git diff doesn't show it nicely, this PR rearranges the steps in the build command. Previously, there were multiple loops over all images. Now, each image is pushed immediately after it is built so ImageBuilder can attach the metadata referrer to the exact pushed image digest. Here is a high-level before/after comparison:

Before:

Build:
- Pull base images
- For each image:
  - Build image
- For each image:
  - Push image
- For each image:
  - Compute image metadata (base image, layers, URL, etc.)
  - Populate image info
- Write image-info.json

After:

Build:
- Pull base images
- For each image:
  - Build image
  - Push image
  - Compute image metadata (base image, layers, URL, etc.)
  - Attach metadata referrer
  - Populate image info
- Write image-info.json

Note: referrer annotations are not inherited by downstream images.

+                manifestServiceFactory: CreateManifestServiceFactoryMock(
+                    localImageDigestResults: [new(baseImageTag, baseImageDigest)]).Object,
+                imageCacheService: new ImageCacheService(Mock.Of<ILogger<ImageCacheService>>(), Mock.Of<IGitService>()));
+            command.Options.Manifest = Path.Combine(tempFolderContext.Path, "manifest.json");


+            command.Options.SourceRepoUrl = sourceRepoUrl;
+
+            const string runtimeRelativeDir = "1.0/runtime/os";
+            Directory.CreateDirectory(Path.Combine(tempFolderContext.Path, runtimeRelativeDir));


+
+            const string runtimeRelativeDir = "1.0/runtime/os";
+            Directory.CreateDirectory(Path.Combine(tempFolderContext.Path, runtimeRelativeDir));
+            string dockerfileRelativePath = Path.Combine(runtimeRelativeDir, "Dockerfile");


+            const string runtimeRelativeDir = "1.0/runtime/os";
+            Directory.CreateDirectory(Path.Combine(tempFolderContext.Path, runtimeRelativeDir));
+            string dockerfileRelativePath = Path.Combine(runtimeRelativeDir, "Dockerfile");
+            string dockerfileAbsolutePath = PathHelper.NormalizePath(Path.Combine(tempFolderContext.Path, dockerfileRelativePath));


+                    CreateImage(
+                        new Platform[] { platform })));
+
+            File.WriteAllText(Path.Combine(tempFolderContext.Path, command.Options.Manifest), JsonConvert.SerializeObject(manifest));


+            command.Options.Manifest = Path.Combine(tempFolderContext.Path, "manifest.json");
+
+            const string runtimeRelativeDir = "1.0/runtime/os";
+            Directory.CreateDirectory(Path.Combine(tempFolderContext.Path, runtimeRelativeDir));


+
+            const string runtimeRelativeDir = "1.0/runtime/os";
+            Directory.CreateDirectory(Path.Combine(tempFolderContext.Path, runtimeRelativeDir));
+            string dockerfileRelativePath = Path.Combine(runtimeRelativeDir, "Dockerfile");


+            const string runtimeRelativeDir = "1.0/runtime/os";
+            Directory.CreateDirectory(Path.Combine(tempFolderContext.Path, runtimeRelativeDir));
+            string dockerfileRelativePath = Path.Combine(runtimeRelativeDir, "Dockerfile");
+            string dockerfileAbsolutePath = PathHelper.NormalizePath(Path.Combine(tempFolderContext.Path, dockerfileRelativePath));


+                    CreateImage(
+                        new Platform[] { platform })));
+
+            File.WriteAllText(Path.Combine(tempFolderContext.Path, command.Options.Manifest), JsonConvert.SerializeObject(manifest));


mthalman · 2026-07-01T14:53:09Z

+                                IEnumerable<TagInfo> tagsForDigest = imageArtifactDetails is null ? [] : concreteTags;
+
+                                // Log in again to refresh token as it may have expired from a long build
+                                await ExecuteWithDockerCredentialsAsync(


What are the perf consequences of running this for every single image that gets built?

I'm testing it internally and I'll get back to you.

This comment is still relevant.

mthalman · 2026-07-01T14:55:07Z

+                    string? digest = null;
+                    for (int attempt = 0; attempt <= RetryHelper.MaxRetries && digest is null; attempt++)
+                    {
+                        digest = await imageDigestCache.GetLocalImageDigestAsync(tag.FullyQualifiedName, Options.IsDryRun);


Include some sort of timing backoff for each attempt.

I'm going to take a second pass at this method. This is not how we should do retries. Thanks for calling it out.

This comment is still relevant.

mthalman · 2026-07-01T15:02:08Z

+                                string repoRoot = _gitService.GetRepoRoot(platform.DockerfilePath);
+                                labels[ImageBuilderLabels.Dockerfile] =
+                                    PathHelper.NormalizePath(Path.GetRelativePath(repoRoot, platform.DockerfilePath));


Use GitServiceExtensions.GetDockerfileCommitUrl instead?

This is a workaround for #2165. Additionally, since the source URL is already present in the org.opencontainers.image.source label, including the repo base URL a second time in another label is not necessary. That's why I chose only the Dockerfile path here.

If we already have org.opencontainers.image.source then why do we need this label?

+                manifestServiceFactory: CreateManifestServiceFactoryMock().Object,
+                imageCacheService: new ImageCacheService(Mock.Of<ILogger<ImageCacheService>>(), Mock.Of<IGitService>()),
+                orasServiceFactory: orasServiceFactoryMock.Object);
+            command.Options.Manifest = Path.Combine(tempFolderContext.Path, "manifest.json");


…teAsync

Removes the `--label` build-metadata mechanism from the image build path in preparation for attaching the same metadata as an OCI referrer artifact. The `labels` parameter is dropped from `IDockerService.BuildImage` (and its `DockerService`/`DockerServiceCache` implementations) along with the label-building block in `BuildCommand`. The corresponding label-verification tests are removed and the `BuildImage` mock verifications are updated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Attaches image build metadata (source repo, revision, Dockerfile path, and base image name/digest) to each freshly built and pushed platform image as an OCI referrer artifact whose annotations carry the metadata, rather than baking it into the image as Docker labels. Referrer annotations do not propagate to downstream images and can evolve independently of the image, per #2166. The metadata is recorded using annotation keys in ImageBuilder's own `com.microsoft.imagebuilder.*` namespace rather than the standard `org.opencontainers.image.*` keys. OCI annotations describe the artifact they are placed on; on a referrer artifact the standard keys would describe the referrer itself rather than the subject image, so a custom namespace is used. After pushing a platform, `BuildCommand` builds the annotations inline and attaches them to the pushed image by digest via an `IOrasService` (created from the command's registry credentials) using the new `OciArtifactType.ImageInfoReferrer` artifact type. The `ImageBuilderLabels` constants type is replaced by `ImageBuilderAnnotations`. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Aligns the image build metadata annotation keys with the existing `vnd.microsoft.artifact.lifecycle.*` annotations used for end-of-life metadata, moving them from `com.microsoft.imagebuilder.*` to `vnd.microsoft.imagebuilder.*`. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The build-metadata referrer carries all of its data in manifest annotations and has no content blob. Using a custom '+json' artifact type wrongly implies a JSON payload, so use the empty OCI artifact type (application/vnd.oci.empty.v1+json) instead, matching the behavior of 'oras attach' with no files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR adds an OCI referrer artifact that records ImageBuilder build metadata (as annotations) for each pushed platform image, enabling consumers to discover source/base-image provenance without inheriting labels into downstream images. It also restructures the build flow to build → push → compute metadata → attach referrer per platform so the referrer can be bound to the exact pushed digest.

Changes:

Add ImageBuilder-specific annotation keys and a new OCI artifact type (application/vnd.microsoft.imagebuilder.image-info.v1) for the metadata referrer.
Extend Git utilities to reliably locate the repo root (including worktree/submodule .git file scenarios) and use that to record Dockerfile paths relative to repo root.
Refactor BuildCommand to push each platform immediately after building and then attach the metadata referrer; add unit tests validating referrer attachment behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/ImageBuilder/Oras/OciArtifactType.cs	Adds a constant for the ImageBuilder image-info referrer artifact type.
src/ImageBuilder/ImageBuilderAnnotations.cs	Introduces well-defined annotation keys used on the referrer manifest to describe the subject image.
src/ImageBuilder/IGitService.cs	Adds `GetRepoRoot` API to locate a repository root for a given path.
src/ImageBuilder/GitService.cs	Implements `GetRepoRoot` by delegating to `GitHelper`.
src/ImageBuilder/GitHelper.cs	Refactors commit SHA retrieval to use a shared repo-root discovery routine; supports `.git` as file or directory.
src/ImageBuilder/Commands/BuildCommand.cs	Reworks the build loop to push per-platform and attach an OCI referrer artifact with annotations after push.
src/ImageBuilder/Commands/Build/ImageArtifactDetailsExtensions.cs	Adds helper to enumerate all `PlatformData` entries from `ImageArtifactDetails`.
src/ImageBuilder.Tests/BuildCommandTests.cs	Adds tests covering attaching/skipping the metadata referrer and updates existing mocks for new git API.

+                    string? digest = null;
+                    for (int attempt = 0; attempt <= RetryHelper.MaxRetries && digest is null; attempt++)
+                    {
+                        digest = await imageDigestCache.GetLocalImageDigestAsync(tag.FullyQualifiedName, Options.IsDryRun);
+                    }


+internal static class ImageArtifactDetailsExtensions
+{
+    /// <summary>
+    /// Enumerates all platform data entries from image-info repo and image groups.


lbussell requested review from baronfel and mthalman July 1, 2026 01:04

github-code-quality Bot found potential problems Jul 1, 2026

View reviewed changes

mthalman reviewed Jul 1, 2026

View reviewed changes

lbussell mentioned this pull request Jul 1, 2026

Rework container image rebuilds #2166

Open

6 tasks

lbussell force-pushed the lbussell/use-labels-2 branch from ad2da9b to 5fe71e3 Compare July 9, 2026 02:34

lbussell changed the title ~~Add image labels for base image, base image digest, and source~~ Add referrer with annotations for image source and base image name + digest Jul 9, 2026

github-code-quality Bot found potential problems Jul 9, 2026

View reviewed changes

lbussell and others added 10 commits July 8, 2026 19:41

Make BuildCommand less stateful and lift some control flow into Execu…

f77ba54

…teAsync

Push images immediately after building

6a5bf5b

Add labels to images

61621ec

Add custom Dockerfile label

7bff227

Handle worktrees in GetRepoRoot

9ade0d0

Fix BuildCommandTests ORAS namespace after rebase

27b987a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

lbussell force-pushed the lbussell/use-labels-2 branch from 5fe71e3 to 27b987a Compare July 9, 2026 02:47

lbussell and others added 3 commits July 8, 2026 19:49

Restore BuildCommandTests BOM

ac9c07a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Clean up unnecessary post-rebase diffs

42b2295

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Use ImageBuilder artifact type for metadata referrer

11c4adc

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

lbussell marked this pull request as ready for review July 9, 2026 03:24

lbussell requested a review from a team as a code owner July 9, 2026 03:24

mthalman requested a review from Copilot July 9, 2026 13:48

Copilot started reviewing on behalf of mthalman July 9, 2026 13:49 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add referrer with annotations for image source and base image name + digest#2163

Add referrer with annotations for image source and base image name + digest#2163
lbussell wants to merge 13 commits into
mainfrom
lbussell/use-labels-2

lbussell commented Jul 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

mthalman Jul 1, 2026

Uh oh!

lbussell Jul 1, 2026

Uh oh!

mthalman Jul 9, 2026

Uh oh!

mthalman Jul 1, 2026

Uh oh!

lbussell Jul 1, 2026

Uh oh!

mthalman Jul 9, 2026

Uh oh!

mthalman Jul 1, 2026

Uh oh!

lbussell Jul 1, 2026 •

edited

Loading

Uh oh!

mthalman Jul 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

lbussell commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change to the build command's execution flow

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lbussell Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lbussell commented Jul 1, 2026 •

edited

Loading

lbussell Jul 1, 2026 •

edited

Loading